---
title: Stripe App Sandbox
sidebarTitle: Stripe App Sandbox
---

import Overview from "/snippets/overview.mdx"
import PreBuiltTooling from "/snippets/generated/stripe-app-sandbox/PreBuiltTooling.mdx"
import PreBuiltUseCases from "/snippets/generated/stripe-app-sandbox/PreBuiltUseCases.mdx"

import { StatusWidget } from "/snippets/api-down-watch/status-widget.jsx"

<StatusWidget service="stripe" />

<Overview />
<PreBuiltTooling />
<PreBuiltUseCases />

| Pre-Requisites        | Status | Comment                                                                                                                                                                                             |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Paid dev account**  | ✅      | You must have an activated Stripe account (submit business info). No charges required, but activation is mandatory.                                                                                 |
| **Paid test account** | ✅      | Stripe does not require or support a paid **test** account. Sandbox accounts are available by default in every account.                                                                                       |
| **Partnership**       | ✅      | Not required to develop or publish apps, but Stripe may offer [partnership](https://docs.stripe.com/partners#:~:text=To%20become%20a%20Stripe%20partner,the%20Stripe%20Partner%20Ecosystem%20Agreement.) options for higher visibility.                                                                                                                        |
| **App review**        | ❌      | Required if you want to publish the app publicly on the Stripe App Marketplace. Stripe will review your app before approval.                                                                        |
| **Security audit**    | ✅     | Not strictly required, but apps must follow Stripe’s [security best practices](https://stripe.com/docs/security). A formal audit may be needed depending on your app’s access level and data usage. |


## Setup guide

<Steps>
  <Step title="Create a Stripe account">
    If you don't already have one, sign up for a [Stripe account](https://dashboard.stripe.com/register).
  </Step>
  <Step title="Install Stripe CLI">
    1. If you haven't already, install the [Stripe CLI](https://docs.stripe.com/stripe-cli#install).
    2. Log in using your Stripe account:
       ```shell
       stripe login
       ```
  </Step>

  <Step title="Install the Stripe Apps CLI plugin">
    1. Run the following command to install the Stripe Apps plugin:
       ```shell
       stripe plugin install apps
       ```
    2. Verify the plugin version is 1.5.12 or newer:
        ```shell
        stripe apps -v
        ```
  </Step>

  <Step title="Create your Stripe App">
    1. Create a new app project using the CLI:
       ```shell
       stripe apps create my-stripe-app
       ```
    2. This creates a local project folder with a manifest and app code.
  </Step>

  <Step title="Edit the app manifest">
    Open the **stripe-app.json** file and update these fields:
    - **stripe_api_access_type**: Set to **oauth**
    - **distribution_type**: Set to **public**
    - **allowed_redirect_uris**: Add your redirect URI as **https://api.nango.dev/oauth/callback**
    - **sandbox_install_compatible**: Set to **true**
    Example:
    ```json
    {
      "id": "com.example.my-app",
      "version": "0.0.1",
      "name": "My Stripe App",
      "icon": "./icon.png",
      "permissions": [],
      "stripe_api_access_type": "oauth",
      "distribution_type": "public",
      "sandbox_install_compatible": true,
      "allowed_redirect_uris": [
        "https://api.nango.dev/oauth/callback"
      ]
    }
    ```
  </Step>

  <Step title="Add required permissions and UI (optional)">
    1. Add [permissions](https://docs.stripe.com/stripe-apps/reference/permissions) your app requires to access Stripe resources in the manifest (e.g., **read_only**, **customers:read**, etc.).
    ```json
    "permissions": [
        {
            "permission": "customer_read",
            "purpose": "Receive access to the customer’s phone number"
        }
    ]
  ```
    2. Optionally add a **settings view** or other UI extensions if your app has a user-facing configuration.
  </Step>
  <Step title="Upload your app to Stripe (requires live account)">
    1. Ensure you're logged into a fully activated (non-sandbox) Stripe account.
    2. Upload your app to Stripe:
       ```shell
       stripe apps upload
       ```
    <Note>[Sandbox accounts](https://docs.stripe.com/stripe-apps/enable-sandbox-support#enable-sandbox-installs-for-your-public-app) cannot upload apps. You must activate your account first.</Note>
  </Step>


<Step title="Obtain your Client ID and Client Secret">
  1. Go to your app's details page in the Stripe Dashboard.
  2. Open the <strong>External test</strong> tab.
  3. Click <strong>Get started</strong> if you haven’t already configured the external test OAuth setup.
  4. After setup, Stripe will generate OAuth installation links in the **Test OAuth** section. Your <strong>Client ID</strong> will be included in the **Sandbox link** as a query parameter (e.g., <code>client_id=...</code>).
  5. To obtain your <strong>Client Secret</strong>, go to the <strong>API Keys</strong> page in the Stripe Dashboard and copy your <strong>Secret key</strong> (starts with <code>sk_test_...</code>).

  ⚠️ Make sure that your <strong>client_id</strong> and <strong>secret key</strong> come from the same Stripe sandbox account and environment. Mixing keys from different environments or accounts will result in authorization errors like <em>"Authorization code provided does not belong to you."</em>
  Save these credentials securely as you'll need them when configuring your integration in Nango.
</Step>

  <Step title="Next">
    Follow the [_Quickstart_](/getting-started/quickstart).
  </Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>

<UsefulLinks />

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/stripe-app.mdx)</Note>

<CommonScopes />

## API gotchas

- The Stripe App Sandbox is a test environment that simulates real installs and OAuth flows without affecting live data. Use it for external development or testing purposes.

<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/stripe-app.mdx)</Note>

<Card title="Connect to Stripe App Sandbox" icon="link" href="/integrations/all/stripe-app-sandbox/connect" horizontal>
  Guide to connect to Stripe App Sandbox using Connect UI
</Card>
